home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Magnum One
/
Magnum One (Mid-American Digital) (Disc Manufacturing).iso
/
d12
/
asmwiz10.arc
/
ASMWIZ.DOC
next >
Wrap
Text File
|
1990-04-06
|
26KB
|
626 lines
The Assembly Wizard's Library
ASMWIZ Copyright (c) 1990 Thomas G. Hanlin III
This is ASMWIZ, a library of assembly language routines for assembly language
programmers. It is copyrighted and may be distributed only under the
following conditions:
1) No fee of over $5.00 may be charged for distribution. This restriction
applies only to physical copies and is not meant to prevent
distribution by telecommunication.
2) All ASMWIZ files must be distributed together in original, unaltered
form. This includes ASMWIZ.DOC, ASMWIZ.MAN, ASMWIZ.NEW, ASMWIZ.XRF,
CREATE.BAT, EXAMPLE.ASM, EXAMPLE.COM, FILES.LST, and REGISTER.TXT.
You use this library at your own risk. It has been tested by me on my own
computer, but I will not assume any responsibility for any problems which
ASMWIZ may cause you. If you do encounter a problem, please let me know
about it, and I will do my best to verify and repair the error.
It is expected that if you find ASMWIZ useful, you will register your copy.
This entitles you to receive the latest version of ASMWIZ on a 5 1/4" disk,
complete with full source code. The source code is designed for the OPTASM
assembler by SLR Systems and may require minor modifications to assemble
under MASM or TASM. See REGISTER.TXT for more information.
*** Limited-time Offer ***
Those who register ASMWIZ before May 1, 1990, will receive a free upgrade to
the next version of ASMWIZ.
The ASMWIZ library was designed for use with small assembly programs and is
compatible with the creation of COM files. All CALLs are of the NEAR
variety. If there is sufficient interest, a FAR model will also be made.
For an example of how to set up your program to access the ASMWIZ library,
how to LINK the routines, and so forth, see the EXAMPLE.ASM, EXAMPLE.COM,
and CREATE.BAT files.
Note that DOS-dependent services expect DOS 2.0 or higher versions, unless
otherwise specified.
Services to be added in future versions include screen save/restore, support
for Hercules/CGA/EGA/VGA graphics, additional mouse handling, keyboard
control and input services, flexible file handling with automatic network
support and buffering, expanded and extended memory support, background
music, ANSI emulation, communications, and much more. If there is something
in particular that you'd like to see, please let me know about it.
Base Conversion Services
The Base Conversion Services provide the ability to convert back and forth
between a number and its ASCIIZ representation. Any base from 2-36 may be
employed, so these routines encompass binary, decimal, hex and octal
conversions. Services are provided for integers and long integers, both
signed and unsigned.
The following services are available:
BC_ASC2INT convert an ASCIIZ string to an unsigned integer
BL <-- base from which to convert
DS:SI <-- ptr to string
-------
AX = unsigned integer
BC_ASC2LONG convert an ASCIIZ string to an unsigned long integer
BL <-- base from which to convert
DS:SI <-- ptr to string
-------
DX,AX = unsigned long integer
BC_ASC2SINT convert an ASCIIZ string to a signed integer
BL <-- base from which to convert
DS:SI <-- ptr to string
-------
AX = signed integer
BC_ASC2SLONG convert an ASCIIZ string to a signed long integer
BL <-- base from which to convert
DS:SI <-- ptr to string
-------
DX,AX = signed long integer
BC_INT2ASC convert an unsigned integer to an ASCIIZ string
AX <-- unsigned integer
BL <-- base to which to convert
ES:DI <-- ptr to string buffer (recommend 17 bytes)
BC_LONG2ASC convert an unsigned long integer to an ASCIIZ string
DX,AX <-- unsigned long integer
BL <-- base to which to convert
ES:DI <-- ptr to string buffer (recommend 33 bytes)
BC_SINT2ASC convert a signed integer to an ASCIIZ string
AX <-- signed integer
BL <-- base to which to convert
ES:DI <-- ptr to string buffer (recommend 18 bytes)
BC_SLONG2ASC convert a signed long integer to an ASCIIZ string
DX,AX <-- signed long integer
BL <-- base to which to convert
ES:DI <-- ptr to string buffer (recommend 34 bytes)
Delay Services
The Delay Services are for those times when you want the computer to sit
around doing nothing for a while. Delays of various timing resolution are
available for anything from small to large waits.
Note that timers 0-1 may be used by ASMWIZ itself. See ASMWIZ.MAN for more
details on the 100th-second delay services.
The following services are available:
MD_DELAY delay for a number of 100ths of seconds
CX <-- delay (0-32767)
MD_DONE terminate 100th-second delay handler
MD_GETTIMER get a delay count
AL <-- timer number (0-3)
-------
CX = delay * 2 (0-65534)
MD_INIT initialize 100th-second delay handler
MD_SETTIMER set a delay count
AL <-- timer number (0-3)
CX <-- delay (0-32767)
MD_TICK delay for a number of clock ticks (18ths of seconds)
CX <-- delay (0-65535)
Math (32-bit) Services
The Math Services provide support for the basic arithmetic operations on
unsigned long integers. They allow you to add two 32-bit integers, subtract
one 32-bit integer from another, multiply two 32-bit integers (giving a
64-bit result), and divide a 63-bit integer by a 32-bit integer (giving a
32-bit result and 32-bit remainder).
Since 32-bit integers are rather unwieldy unless you're using an 80386 or
above (in which case you don't need these services anyway), the numbers are
passed back and forth through a buffer in memory.
The following services are available:
MA_ADD32 add two unsigned long integers
DS:SI <-- first operand
DS:SI+4 <-- second operand
-------
DS:SI+8 = result
MA_DIV32 divide an unsigned 63-bit integer by an unsigned long integer
DS:SI <-- dividend (64 bits: high bit must be zero)
DS:SI+8 <-- divisor (unsigned long integer)
-------
DS:SI+12 = quotient (unsigned long integer)
DS:SI+16 = remainder (unsigned long integer)
MA_MUL32 multiply two unsigned long integers
DS:SI <-- first operand
DS:SI+4 <-- second operand
-------
DS:SI+8 = result (unsigned very long integer: 64 bits)
MA_SUB32 subtract one unsigned long integer from another
DS:SI <-- first operand
DS:SI+4 <-- second operand
-------
DS:SI+8 = result
Memory Services
The Memory Services provide low-level routines for memory manipulation. They
allow you to manipulate addresses, as well as providing a "smart" block move
service that automatically handles overlaps between source and destination
areas.
Among the address manipulation services are routines to convert an address to
have the smallest possible segment and highest possible offset (or vice
versa) to allow REP operations to always handle up to 65,519 bytes without
wrapping within the segment.
The following services are available:
ME_HIGHOFS convert an address to have the lowest segment & highest offset
DX:AX <-- segment:offset
-------
DX:AX = converted segment:offset
ME_LOWOFS convert an address to have the highest segment & lowest offset
DX:AX <-- segment:offset
-------
DX:AX = converted segment:offset
ME_MOVE move a block of memory without overlap conflicts
DS:SI <-- source segment:offset
ES:DI <-- destination segment:offset
CX <-- bytes to move (0 - 65,519)
Miscellaneous Services
The Miscellaneous Services provide a number of services for various purposes,
such as parsing the command line, scanning the environment for a
parameter, and generating pseudo-random numbers. They eliminate much of the
tedium of these common chores.
The following services are available:
MI_BOOT reboot the computer (warm boot)
MI_MATCHFILE see if a filename matches a specified pattern
DS:SI <-- pattern (may contain wildcards)
ES:DI <-- filename (may not contain drive or path specs)
-------
flags = ZF if the filename matches the pattern
NZ if the filename doesn't match the pattern
MI_PARSE parse a command line into filespecs and options
DS:SI <-- ptr to command line (for COM files, is CS:0080h)
ES:DI <-- ptr to filename buffer (recommend 128 bytes)
ES:BX <-- ptr to option buffer (recommend 128 bytes)
AL <-- switch character (normally "/" for MS-DOS)
-------
AH = number of options
AL = number of filenames
MI_RANDOM generate a pseudo-random number
DX <-- random number range (1-4000)
-------
AX = random number (0 to DX - 1)
MI_RANDOMIZE initialize the pseudo-random number generator
AX <-- random number seed (use 0FFFFh for auto-seeding)
MI_SCANENV scan the DOS environment for a parameter
DS:SI <-- ptr to the DOS environment or similar table
ES:DI <-- ptr to the parm for which to search
-------
CY if not found
NC if match found; DS:SI points to parm value
Mouse Services
The Mouse Services provide a simple set of functions for dealing with
Microsoft-compatible mouse devices. You may see if a mouse exists, control
the mouse cursor, and get information about the mouse buttons.
The following services are available:
MO_HIDECURSOR hide the mouse cursor
MO_INIT see if a mouse is installed (and if so, how many buttons)
-------
AL = number of buttons on the mouse (zero if no mouse)
MO_LOCATE set the mouse cursor location
DH <-- row (1-25)
DL <-- column (1-80)
MO_RANGE set the mouse cursor range
CH <-- top row (1-25)
CL <-- leftmost column (1-80)
DH <-- bottom row (1-25)
DL <-- rightmost column (1-80)
MO_SHOWCURSOR show the mouse cursor
MO_WHERE get the mouse cursor location and button states
-------
AL = left button (0 = not pressed, 1 = pressed)
AH = right button (0 = not pressed, 1 = pressed)
DH = row (1-25)
DL = column (1-80)
Sound and Music Services
The Sound and Music Services provide the ability to generate sound effects
and music. The current service is rather on the primitive side. It will be
supplemented by a background (interrupt-driven) music command language in a
future version of ASMWIZ.
The following services are available:
MU_SOUND produce a sound of a specified duration and frequency
AX <-- frequency (Hertz; about 50-4000 is useful)
DX <-- duration (18ths of seconds)
Video Text Services
Displaying text is something that almost every program will do. The ASMWIZ
library contains numerous sets of video services which make it easy to use
the display in a consistent manner.
The display services are divided into four sets of routines, each of which
provides similar capabilities:
DOS-level services
BIOS-level services
Machine-level services for text modes
Machine-level services for CGA graphics modes
The DOS services provide the maximum level of compatibility. They are also
the slowest of the video services and the least flexible. The main practical
advantage of using DOS services is that they allow redirection, so the output
of your program can be sent to a file, a printer, or a serial port as well as
to the display. Since DOS itself has only minimal video support, you will
need to make sure an ANSI driver is installed before using these services.
See your DOS manual on ANSI.SYS for more information if you need it.
The BIOS services provide a very good level of compatibility. They are
faster and more flexible than the DOS services. Like the DOS services, these
routines are quite likely to work on nonstandard displays.
The machine-level services are the least compatible. They will work on any
standard PC clone, but not on semi-compatible hardware or with nonstandard
display devices. In return for this disadvantage, these services are much
faster than the other services and provide a great deal more flexibility.
Text Display Speeds
Speed tests were conducted on an 8088 machine with a Phoenix BIOS, running
MS-DOS 3.30. Ratings may vary on other machines and DOS versions. The tests
were conducted on how quickly strings could be printed to the display.
Speeds are listed relative to the slowest display method (DOS services).
+-----------+-----------+-----------+
| DV_STROUT | BV_STROUT | MV_STROUT |
+------------+-----------+-----------+-----------+
| Mode 3 | | | |
| text mode | 100% | 162% | 572% |
+------------+-----------+-----------+-----------+
| Mode 4 | | | |
| CGA lo-res | 100% | 114% | 180% |
+------------+-----------+-----------+-----------+
| Mode 6 | | | |
| CGA hi-res | 100% | 122% | 204% |
+------------+-----------+-----------+-----------+
From this chart, you can see that using BIOS display services is 14% - 62%
faster than using DOS services. Using machine-level services is 80% - 472%
faster than using DOS services, and about 60% - 250% faster than using BIOS
services.
If system compatibility is a major concern, then note that the DOS services
are most compatible, followed by the BIOS services and then the machine-level
services. The price you pay for compatibility is speed and flexibility. The
machine-level services are the fastest and most flexible, followed by the
BIOS services and then the DOS services.
General Video Information
For all text routines, color/attributes are encoded as a single byte value:
bit: 7 6 5 4 3 2 1 0
+---+---+---+---+---+---+---+---+
| B | backgnd | I | foregnd |
+---+---+---+---+---+---+---+---+
B: "blink". Set if the color is blinking.
I: "intense". Set if the foreground color is intense (bright or light).
backgnd, foregnd: the actual foreground and background colors. The bits
specify the red, green, and blue components of the color, giving the
following list of colors:
0 black (if intense, may or may not be displayed as gray)
1 blue
2 green
3 cyan
4 red
5 magenta
6 brown (if intense, is usually displayed as yellow)
7 white
Text in CGA graphics modes is different. If you use BIOS or DOS services,
you may only specify a foreground color, which may be 0-3. If you use the
CGA machine-level services, you may specify a background color as well as a
foreground color. Color encoding is the same as for text mode, with the
exception that there are no "blinking" or "intense" bits, and the color range
is 0-3 instead of 0-7. The 0-3 range does not follow the above color list;
the colors depend instead on which CGA palette is in use.
Screen modes are specified as a single byte, as follows:
Mode Resolu. Type Colr Use Adapter(s) Services
0 40x25 b&w 16 text CGA, EGA, VGA MV, BV, DV
1 40x25 color 16 text CGA, EGA, VGA MV, BV, DV
2 80x25 b&w 16 text CGA, EGA, VGA MV, BV, DV
def- 3 80x25 color 16 text CGA, EGA, VGA MV, BV, DV
4 320x200 color 4 graphics CGA, EGA, VGA CG, BV, DV
5 320x200 b&w 4 graphics CGA, EGA, VGA CG, BV, DV
6 640x200 color 2 graphics CGA, EGA, VGA CG, BV, DV
mda- 7 80x25 b&w - text MDA, EGA, VGA BV
13 320x200 color 16 graphics EGA, VGA BV
14 640x200 color 16 graphics EGA, VGA BV
15 640x350 mono - graphics EGA, VGA BV
16 640x350 color 16 graphics EGA, VGA BV
17 640x480 color 2 graphics VGA BV
18 640x480 color 16 graphics VGA BV
19 320x200 color 256 graphics VGA BV
BV = BIOS video services DV = DOS video services
MV = Machine-level text services CG = Machine-level CGA graphics services
Video Service List
All of the video services share a common nomenclature and calling procedure.
For many of the services, you will have a choice of whether to use DOS, BIOS,
Machine-level (text modes), or Machine-level (CGA graphics modes). The level
is specified as a two-letter code prefix to the routine name, where the codes
are as follows:
DV DOS Video
BV BIOS Video
MV Machine-level (text mode) Video
CG Machine-level (CGA graphics mode) Video
The routine to display a string using DOS services, for example, is named
DV_STROUT (DOS Video service, String Output). It usually isn't a good idea
to "mix and match" video services of different types.
The following services are available:
CHROUT display a character BV,DV,MV,CG
AL <-- character
CLS clear the screen and home the cursor BV,DV,MV,CG
COLOR set the text color BV,DV,MV,CG
AL <-- color/attribute
CRLF display a carriage return and a linefeed BV,DV,MV,CG
CLEOLN clear from the cursor to the end of the line BV,DV,MV,CG
DELCHR delete the character at the cursor , ,MV,
DELLINE delete the current line BV,dv,MV,
GETCOLOR get the text color BV, ,MV,CG
AL = color/attribute
HIDECURSOR hide the cursor BV, ,MV,
INIT initialize the video service routines MV,CG
INSCHR insert a space at the cursor , ,MV,
INSLINE insert a row at the current line BV,dv,MV,
LOCATE set the cursor position BV,DV,MV,CG
DH <-- row (1-25), DL <-- column (1-40/80)
MODE set the screen mode BV,DV,MV,CG
AL <-- mode (see General Video Information)
POPUP display a pop-up window BV, ,MV,
DX <-- parameter pointer
SHOWCURSOR show the cursor BV, ,MV,
STROUT display a string BV,DV,MV,CG
DS:DX <-- pointer to ASCIIZ string
WHERE get the current cursor position BV, MV,CG
DH = row (1-25), DL = column (1-40/80)
String Services (ASCIIZ)
The ASCIIZ String Services provide a wide assortment of services for dealing
with null-terminated strings.
Note that, although many of the string services are designed to place the
result of processing a first string into a second string, it is not actually
necessary to use two string buffers. The services are designed so that you
can place the results back into the original string buffer by using the same
address for both strings.
The following routines are included amongst the ASCIIZ String Services:
S0_COMPARE compares two strings
DS:SI <-- first string
ES:DI <-- second string
Flags = ZF if equal, NZ if not equal
CY if first < second, NC if first >= second
S0_DUPE forms a string by duplicating a character
ES:DI <-- result string
AL <-- character to duplicate
CX <-- number of times to repeat the character
S0_LEFT copies a specified section from the left of a string
DS:SI <-- source string
CX <-- number of characters to copy
ES:DI <-- result string
S0_LENGTH gets the length of a string (excluding the null terminator)
DS:SI <-- string
CX = string length
S0_LOCASE converts a string to lowercase (international)
DS:SI <-- source string
ES:DI <-- result string
S0_MID copies a specified section of a string
DS:SI <-- source string
DX <-- where to start copying from (1-xx)
CX <-- how many characters to copy
ES:DI <-- result string
S0_RIGHT copies a specified section from the right of a string
DS:SI <-- source string
CX <-- number of characters to copy
ES:DI <-- result string
S0_TRIM trims the "white space" (blanks and control characters) from
either side (or both sides) of a string
DS:SI <-- source string
AL <-- set bit 0 to trim the left, bit 1 for right
ES:DI <-- result string
S0_UPCASE converts a string to uppercase (international)
DS:SI <-- source string
ES:DI <-- result string
Telecommunications Services
The Telecommunications Services provide functions that are useful for
telecommunications. This includes services for manipulating the serial port
and services that aid in performing file transfers and similar functions.
The following routines are included amongst the Telecommunications Services:
TC_CHKSUM calculate the Xmodem/Ymodem checksum of a block of data
DS:SI <-- pointer to a data block
CX <-- length of data block (in bytes)
-------
AX = checksum
TC_CRC calculate the Xmodem/Ymodem CRC of a block of data
DS:SI <-- pointer to a data block
CX <-- length of data block (in bytes)
-------
AX = resulting CRC
Time and Date Services
The Time and Date Services provide international date handling. Based on the
country code given it by DOS, these services return strings that represent
the current time or date in the appropriate format for that country.
These services provide a simple way to make your software work properly on
any computer anywhere, across the world.
See the COUNTRY entry under CONFIG.SYS in your DOS manual for more details.
Note that DOS version 3.0 or greater is required to insure that the date and
time delimiters are appropriate. Otherwise, the date and time formats will
still be correct, but the delimiters used will be assumed to be "-" for the
date and ":" for the time. With DOS versions before 3.0, the time will be
presented in 12-hour (am/pm) format.
The following routines are included amongst the Time and Date Services:
TD_GETDATE get the current date as an ASCIIZ string
DS:DX <-- pointer to a buffer (minimum 11 bytes)
AL <-- 0 for 2-digit year, 1 for 4-digit year
TD_GETTIME get the current date as an ASCIIZ string
DS:DX <-- pointer to a buffer (minimum 8 bytes)